{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vindex_intro_md"
      },
      "source": [
        "# VariableIndex"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "license_cell",
      "metadata": {
        "tags": [
          "remove-cell"
        ]
      },
      "source": [
        "GTSAM Copyright 2010-2022, Georgia Tech Research Corporation,\nAtlanta, Georgia 30332-0415\nAll Rights Reserved\n\nAuthors: Frank Dellaert, et al. (see THANKS for the full author list)\n\nSee LICENSE for the license information"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vindex_desc_md"
      },
      "source": [
        "A `VariableIndex` provides an efficient way to look up which factors in a `FactorGraph` involve a particular variable (Key). It stores, for each variable, a list of the indices of the factors that include that variable.\n",
        "\n",
        "This structure is often computed internally by GTSAM algorithms (like ordering methods or elimination) but can also be created explicitly if needed, for example, to improve performance when multiple operations need this information."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vindex_colab_md"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/borglab/gtsam/blob/develop/gtsam/inference/doc/VariableIndex.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "vindex_pip_code",
        "tags": [
          "remove-cell"
        ]
      },
      "outputs": [],
      "source": [
        "%pip install --quiet gtsam-develop"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {
        "id": "vindex_import_code"
      },
      "outputs": [],
      "source": [
        "import gtsam\n",
        "from gtsam import VariableIndex, Ordering\n",
        "# Need a graph type for creation\n",
        "from gtsam import SymbolicFactorGraph\n",
        "from gtsam import symbol_shorthand\n",
        "\n",
        "X = symbol_shorthand.X\n",
        "L = symbol_shorthand.L"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vindex_create_md"
      },
      "source": [
        "## Creating a VariableIndex\n",
        "\n",
        "A `VariableIndex` is typically created from an existing `FactorGraph`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "vindex_create_code",
        "outputId": "abcdef01-2345-6789-abcd-ef0123456789"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "VariableIndex: nEntries = 13, nFactors = 7\n",
            "var l1: 3 4\n",
            "var l2: 5 6\n",
            "var x0: 0 1 3\n",
            "var x1: 1 2 4 5\n",
            "var x2: 2 6\n"
          ]
        }
      ],
      "source": [
        "# Create a simple SymbolicFactorGraph\n",
        "graph = SymbolicFactorGraph()\n",
        "graph.push_factor(X(0))           # Factor 0\n",
        "graph.push_factor(X(0), X(1))     # Factor 1\n",
        "graph.push_factor(X(1), X(2))     # Factor 2\n",
        "graph.push_factor(X(0), L(1))     # Factor 3\n",
        "graph.push_factor(X(1), L(1))     # Factor 4\n",
        "graph.push_factor(X(1), L(2))     # Factor 5\n",
        "graph.push_factor(X(2), L(2))     # Factor 6\n",
        "\n",
        "# Create VariableIndex from the graph\n",
        "variable_index = VariableIndex(graph)\n",
        "\n",
        "# Print the index\n",
        "variable_index.print(\"VariableIndex: \")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vindex_access_md"
      },
      "source": [
        "## Accessing Information\n",
        "\n",
        "You can query the number of variables, factors, and entries, and look up the factors associated with a specific variable."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 5,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "vindex_access_code",
        "outputId": "bcdef012-3456-789a-bcde-f0123456789a"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Number of variables (size): 5\n",
            "Number of factors (nFactors): 7\n",
            "Number of variable-factor entries (nEntries): 13\n",
            "Factors involving x1: [1, 2, 4, 5]\n",
            "Factors involving l1: [3, 4]\n"
          ]
        }
      ],
      "source": [
        "print(f\"Number of variables (size): {variable_index.size()}\")\n",
        "print(f\"Number of factors (nFactors): {variable_index.nFactors()}\")\n",
        "print(f\"Number of variable-factor entries (nEntries): {variable_index.nEntries()}\")\n",
        "\n",
        "# Get factors involving a specific variable\n",
        "factors_x1 = variable_index.at(X(1)) # Returns a FactorIndices (FastVector<size_t>)\n",
        "print(f\"Factors involving x1: {factors_x1}\")\n",
        "\n",
        "# Use key directly\n",
        "factors_l1 = variable_index.at(L(1))\n",
        "print(f\"Factors involving l1: {factors_l1}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vindex_use_md"
      },
      "source": [
        "## Usage in Algorithms\n",
        "\n",
        "`VariableIndex` is primarily used as input to other algorithms, particularly ordering methods like `Ordering.Colamd`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "vindex_use_code",
        "outputId": "cdef0123-4567-89ab-cdef-0123456789ab"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "COLAMD Ordering from VariableIndex: Position 0: l1, x0, x1, l2, x2\n"
          ]
        }
      ],
      "source": [
        "# Compute COLAMD ordering directly from the VariableIndex\n",
        "colamd_ordering = Ordering.Colamd(variable_index)\n",
        "colamd_ordering.print(\"COLAMD Ordering from VariableIndex: \")"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "display_name": "gtsam",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.13.1"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}